Liquid Glass Effect#

Scripting provides full support for the new Liquid Glass visual system introduced in iOS 26. This includes glassEffect, GlassEffectContainer, UIGlass, and related geometry-matching and transition APIs. These APIs allow scripts to create rich translucent materials, fluid glass shapes, matched geometry animations, and unioned glass regions directly within TSX.

This document explains how the Liquid Glass APIs are used in Scripting, including:

• Concepts and fundamentals
• How to apply glass effects
• UIGlass configuration
• Geometry transitions
• glassEffect identifiers and unions
• GlassEffectContainer behavior
• Practical examples and best practices

1. Overview of Liquid Glass#

Liquid Glass is a new material and animation system in iOS 26. Compared to earlier blur or material effects, Liquid Glass provides:

• Fluid, dynamic shapes that follow view geometry
• Tintable and interactive glass materials
• Geometry-matched transitions
• Grouped “glass unions” to merge multiple regions
• High-performance rendering inside containers

2. The glassEffect Modifier#

Any view that adopts GlassProps can apply a Liquid Glass effect using the glassEffect property.

Definition#

1type GlassProps = {
2  glassEffect?: boolean | UIGlass | Shape | {
3    glass: UIGlass
4    shape: Shape
5  }
6
7  glassEffectTransition?: GlassEffectTransition
8
9  glassEffectID?: {
10    id: string | number
11    namespace: NamespaceID
12  }
13
14  glassEffectUnion?: {
15    id: string | number
16    namespace: NamespaceID
17  }
18}

2.1 Ways to Use glassEffect#

1. Enable default Liquid Glass material#

1<Text glassEffect>Foo</Text>

Equivalent to UIGlass.regular().

2. Apply a specific UIGlass instance#

1<Text glassEffect={UIGlass.regular().interactive(false)}>
2  Foo
3</Text>

You can chain configuration calls such as interactive() and tint().

3. Provide a specific Shape#

1<Text
2  glassEffect={{
3    glass: UIGlass.regular(),
4    shape: { type: 'rect', cornerRadius: 10 }
5  }}
6>
7  Foo
8</Text>

Or directly provide a Shape object:

1<Text glassEffect={{ type: 'rect', cornerRadius: 10 }}>
2  Foo
3</Text>

The glass material will be clipped to the shape’s geometry.

4. Boolean shorthand#

1<View glassEffect />

Acts the same as default Liquid Glass material.

3. The UIGlass Class#

UIGlass represents the Liquid Glass material configuration.

Static factories#

Instance configuration#

1interactive(value?: boolean): UIGlass
2tint(color: Color): UIGlass

Example:

1glassEffect={UIGlass.regular().interactive().tint("red")}

4. Glass Effect Transitions#

1type GlassEffectTransition = 'identity' | 'materialize' | 'matchedGeometry'

Transition Types#

Usage#

1<Text
2  glassEffect
3  glassEffectTransition="materialize"
4>
5  Foo
6</Text>

matchedGeometry works best with glassEffectID or glassEffectUnion.

5. glassEffectID and glassEffectUnion#

Liquid Glass can identify or group glass effects to create smooth geometry animations or unified material regions.

5.1 glassEffectID#

Assigns a unique identity to a glass effect for matched geometry animations.

1<Text
2  glassEffect
3  glassEffectID={{ id: "avatar", namespace }}
4>
5  Foo
6</Text>

Views with the same id + namespace can participate in matched geometry transitions.

5.2 glassEffectUnion#

Groups multiple glass effects into a single unioned glass region.

1<Text
2  glassEffect
3  glassEffectUnion={{ id: 1, namespace }}
4/>

This merges material rendering across multiple views.

6. GlassEffectContainer#

GlassEffectContainer is used to group and manage correlated glass effects. Views inside the container:

• Participate in matched geometry
• Support glass unions
• Render glass transitions more efficiently

Example#

1<GlassEffectContainer>
2  <HStack spacing={40}>
3    <Image systemName="1.circle" glassEffect />
4    <Image systemName="2.circle" glassEffect />
5  </HStack>
6</GlassEffectContainer>

No configuration is required; the container acts as a shared environment.

7. Glass Button Styles#

Scripting supports additional iOS 26 button styles:

• "glass"
• "glassProminent"

Examples#

1<Button title="Glass" buttonStyle="glass" />
2
3<Button title="Glass Prominent" buttonStyle="glassProminent" />
4
5<Button
6  title="Glass & Tint"
7  buttonStyle="glass"
8  tint="red"
9/>

These styles use Liquid Glass materials and integrate with tint and interaction behaviors.

8. Practical Example#

Below is a real example combining multiple features:

• Glass buttons
• GlassEffectContainer
• UIGlass configurations
• Shape-based glass
• Offset effects

1<GlassEffectContainer>
2  <HStack spacing={40}>
3    <Image
4      systemName="1.circle"
5      frame={{ width: 80, height: 80 }}
6      font={36}
7      glassEffect
8      offset={{ x: 30, y: 0 }}
9    />
10    <Image
11      systemName="2.circle"
12      frame={{ width: 80, height: 80 }}
13      font={36}
14      glassEffect
15      offset={{ x: -30, y: 0 }}
16    />
17  </HStack>
18</GlassEffectContainer>

9. Best Practices#

1. Place related glass views inside a single GlassEffectContainer#

Improves performance and produces more consistent transitions.

2. Provide glassEffectID for matched geometry animations#

Without IDs, transitions cannot interpolate shapes.

3. Use glassEffectUnion to merge nearby glass regions#

Creates a seamless material surface.

4. Avoid deeply nested glass hierarchies#

Prefer using a container with ZStack for organization.

5. Use UIGlass.identity when structure must remain but material disabled#

Useful for conditionally enabling glass without changing layout.